docs: Add docs for horizontal orientation by LFDanLu · Pull Request #9843 · adobe/react-spectrum

LFDanLu · 2026-03-25T22:08:27Z

Part of audit

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Check out the docs updates

🧢 Your Project:

RSP

…entation

rspbot · 2026-03-25T22:15:25Z

Build successful! 🎉

LFDanLu · 2026-03-25T22:15:30Z

packages/react-stately/src/layout/ListLayout.ts

  constructor(options: ListLayoutOptions = {}) {
    super();
-    this.rowHeight = options.rowHeight ?? null;
+    this.rowHeight = options?.rowSize ?? options?.rowHeight ?? null;


We could also go ahead and change these height properties to be size as well, would just need to make it back compat with additional getters. Not sure if worth it if those would stick around for quite some time, but might reduce confusion

snowystinger · 2026-03-25T23:18:02Z

packages/react-stately/src/layout/ListLayout.ts

-    this.headingHeight = options.headingHeight ?? null;
-    this.estimatedHeadingHeight = options.estimatedHeadingHeight ?? null;
-    this.loaderHeight = options.loaderHeight ?? null;
+    this.estimatedRowHeight = options?.estimatedRowSize ?? options?.estimatedRowHeight ?? null;


did we want to change all the internal variables to size as well?

o, i think that's what you were saying here #9843 (comment)

yep, thats right. I might try and do it to see how bad it is

Btw, when working on this I was kind of unsure whether to use "size" here, since that typically refers to a 2-dimensional value in the context of our virtualizer package. I think it's fine, but wanted to share it for consideration - naming is hard 😅

haha yeah, I had a similar thought but couldn't think up of a better alternative either. I'll see about pushing up the full changes and then see if we can land on a better name

snowystinger · 2026-03-25T23:20:12Z

starters/docs/src/GridList.css

    grid-template-columns: auto;
    align-items: center;
+
+    &[data-orientation=horizontal] {


Need this in the tailwind starter as well

snowystinger · 2026-03-25T23:23:15Z

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

+    selectionMode="multiple"
+    items={items}
+    style={{display: 'block', padding: 0, height: 100}}>
+    {(item) => <ListBoxItem style={{height: '100%'}}>{item.name}</ListBoxItem>}


We should add some styles to the items so that it's clear where one ends and the next begins. Right now it just looks like a long string of text with some random break in it.

It'd also be nice if this was an example I'd want to use, so if we can make them basically more like cards with a title and description, that'd be better

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

rspbot · 2026-03-26T18:43:08Z

Build successful! 🎉

yihuiliao · 2026-03-26T18:50:17Z

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

+
+Use the `orientation` option to arrange items horizontally or vertically. Provide the same `orientation` on the collection component so keyboard navigation matches the layout.
+
+```tsx render docs={docs.exports.ListLayoutOptions} links={docs.links} props={['gap', 'padding']} initialProps={{estimatedRowSize: 300, gap: 8, padding: 8, orientation: 'horizontal'}} propsObject="layoutOptions" wide


any chance we make the images a tad bit smaller

rspbot · 2026-03-26T23:16:36Z

Build successful! 🎉

snowystinger

smaller images in the cards would be nice, otherwise looks good

Co-authored-by: Yihui Liao <44729383+yihuiliao@users.noreply.github.com>

nwidynski · 2026-03-27T17:45:45Z

@LFDanLu Has the issue found in testing already been taken care of? Otherwise I will open up a PR with a fix for that.

LFDanLu · 2026-03-27T17:46:47Z

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

+  <ListBox
+    /*- begin highlight -*/
+    orientation="horizontal"
+    /*- end highlight -*/
+    aria-label="Horizontal virtualized list"
+    selectionMode="multiple"
+    items={imageOptions}
+    style={{display: 'block', padding: 0, height: 250}}>
+    {(item) => (
+      <ListBoxItem textValue={item.title} aria-label={item.title} style={{height: '100%', padding: 12, overflow: 'hidden', boxSizing: 'border-box', border: '2px solid var(--border-color)', borderRadius: 8}}>
+        <img src={item.image} alt="" style={{maxHeight: 200, aspectRatio: item.aspectRatio, borderRadius: 4}} />
+      </ListBoxItem>
+    )}
+  </ListBox>


@yihuiliao @snowystinger I opted to just go for a simpler change and get rid of the text, was getting a lot of grief with the virtualized card sizing vs getting the img width to be variable and clamped + making the text overflow work without making this example overly complicated

LFDanLu · 2026-03-27T17:48:40Z

@nwidynski mind jogging my memory about what exact issue that was haha.

nwidynski · 2026-03-27T17:49:34Z

I think it was just that the styles I added in storybook spread to the combobox stories (see spreadsheet comment). would also take care of the nits that devon mentioned when approving.

Edit: Seems to have been already done in #9845

rspbot · 2026-03-27T17:50:21Z

Build successful! 🎉

rspbot · 2026-03-27T17:52:16Z

Build successful! 🎉

…release

rspbot · 2026-03-27T20:12:15Z

Build successful! 🎉

rspbot · 2026-03-27T20:12:16Z

## API Changes

react-aria-components

/react-aria-components:TableLayout

 TableLayout <O extends TableLayoutProps = TableLayoutProps, T> {
-  constructor: (ListLayoutOptions) => void
+  constructor: (TableLayoutProps) => void
   getContentSize: () => Size
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getLayoutInfo: (Key) => LayoutInfo | null
   shouldInvalidate: (Rect, Rect) => boolean
   shouldInvalidateLayoutOptions: (TableLayoutProps, TableLayoutProps) => boolean
   update: (InvalidationContext<TableLayoutProps>) => void
   updateItemSize: (Key, Size) => boolean
   useLayoutOptions: () => TableLayoutProps
   virtualizer: Virtualizer<{}, any> | null
 }

/react-aria-components:ListLayoutOptions

 ListLayoutOptions {
   dropIndicatorThickness?: number = 2
-  estimatedHeadingHeight?: number
-  estimatedRowHeight?: number
+  estimatedHeadingSize?: number
+  estimatedRowSize?: number
   gap?: number = 0
-  headingHeight?: number = 48
-  loaderHeight?: number = 48
+  headingSize?: number = 48
+  loaderSize?: number = 48
   orientation?: Orientation = 'vertical'
   padding?: number = 0
-  rowHeight?: number = 48
+  rowSize?: number = 48
 }

/react-aria-components:TableLayoutProps

+TableLayoutProps {
+  columnWidths?: Map<Key, number>
+  dropIndicatorThickness?: number = 2
+  estimatedHeadingHeight?: number
+  estimatedRowHeight?: number
+  gap?: number = 0
+  headingHeight?: number = 48
+  loaderHeight?: number = 48
+  padding?: number = 0
+  rowHeight?: number = 48
+}

@react-spectrum/s2

/@react-spectrum/s2:ListView

 ListView <T extends {}> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean | FocusStrategy
   children: ReactNode | ({}) => ReactNode
   defaultSelectedKeys?: 'all' | Iterable<Key>
   dependencies?: ReadonlyArray<any>
   disabledBehavior?: DisabledBehavior = "all"
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   disallowTypeAhead?: boolean = false
   escapeKeyBehavior?: 'clearSelection' | 'none' = 'clearSelection'
   hideLinkOutIcon?: boolean
   id?: string
   isQuiet?: boolean
   items?: Iterable<T>
   loadingState?: LoadingState
   onAction?: (Key) => void
   onLoadMore?: () => void
   onSelectionChange?: (Selection) => void
-  orientation?: Orientation = 'vertical'
   overflowMode?: 'wrap' | 'truncate' = 'truncate'
   renderActionBar?: ('all' | Set<Key>) => ReactElement
   renderEmptyState?: (GridListRenderProps) => ReactNode
   selectedKeys?: 'all' | Iterable<Key>
   selectionStyle?: 'highlight' | 'checkbox' = 'checkbox'
   shouldSelectOnPressUp?: boolean
   slot?: string | null
   styles?: StylesPropWithHeight
 }

/@react-spectrum/s2:ListViewProps

 ListViewProps <T> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean | FocusStrategy
   children: ReactNode | (T) => ReactNode
   defaultSelectedKeys?: 'all' | Iterable<Key>
   dependencies?: ReadonlyArray<any>
   disabledBehavior?: DisabledBehavior = "all"
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   disallowTypeAhead?: boolean = false
   escapeKeyBehavior?: 'clearSelection' | 'none' = 'clearSelection'
   hideLinkOutIcon?: boolean
   id?: string
   isQuiet?: boolean
   items?: Iterable<T>
   loadingState?: LoadingState
   onAction?: (Key) => void
   onLoadMore?: () => void
   onSelectionChange?: (Selection) => void
-  orientation?: Orientation = 'vertical'
   overflowMode?: 'wrap' | 'truncate' = 'truncate'
   renderActionBar?: ('all' | Set<Key>) => ReactElement
   renderEmptyState?: (GridListRenderProps) => ReactNode
   selectedKeys?: 'all' | Iterable<Key>
   selectionStyle?: 'highlight' | 'checkbox' = 'checkbox'
   shouldSelectOnPressUp?: boolean
   slot?: string | null
   styles?: StylesPropWithHeight
 }

@react-stately/layout

/@react-stately/layout:TableLayout

 TableLayout <O extends TableLayoutProps = TableLayoutProps, T> {
-  constructor: (ListLayoutOptions) => void
+  constructor: (TableLayoutProps) => void
   getContentSize: () => Size
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getLayoutInfo: (Key) => LayoutInfo | null
   shouldInvalidate: (Rect, Rect) => boolean
   shouldInvalidateLayoutOptions: (TableLayoutProps, TableLayoutProps) => boolean
   update: (InvalidationContext<TableLayoutProps>) => void
   updateItemSize: (Key, Size) => boolean
   virtualizer: Virtualizer<{}, any> | null
 }

/@react-stately/layout:ListLayoutOptions

 ListLayoutOptions {
   dropIndicatorThickness?: number = 2
-  estimatedHeadingHeight?: number
-  estimatedRowHeight?: number
+  estimatedHeadingSize?: number
+  estimatedRowSize?: number
   gap?: number = 0
-  headingHeight?: number = 48
-  loaderHeight?: number = 48
+  headingSize?: number = 48
+  loaderSize?: number = 48
   orientation?: Orientation = 'vertical'
   padding?: number = 0
-  rowHeight?: number = 48
+  rowSize?: number = 48
 }

/@react-stately/layout:TableLayoutProps

 TableLayoutProps {
   columnWidths?: Map<Key, number>
   dropIndicatorThickness?: number = 2
   estimatedHeadingHeight?: number
   estimatedRowHeight?: number
   gap?: number = 0
   headingHeight?: number = 48
   loaderHeight?: number = 48
-  orientation?: Orientation = 'vertical'
   padding?: number = 0
   rowHeight?: number = 48
 }

LFDanLu added 4 commits March 25, 2026 11:01

prevent orientation from being exposed in S2 for gridlist

f61d08e

add docs for gridlist orientation

01b5d84

update ListLayoutOptions to clearer names and document horizontal ori…

4a1bba0

…entation

make it a bit smaller

177c7fe

github-actions bot added RAC S2 labels Mar 25, 2026

LFDanLu commented Mar 25, 2026

View reviewed changes

snowystinger reviewed Mar 25, 2026

View reviewed changes

yihuiliao reviewed Mar 26, 2026

View reviewed changes

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx Outdated Show resolved Hide resolved

LFDanLu added 3 commits March 26, 2026 11:05

update virtualizer list example per review

cbfdd67

update gridlist for horizontal

f1250cb

forgot to remove

164706a

yihuiliao reviewed Mar 26, 2026

View reviewed changes

rename rowHeight and other height related properties

c020c54

snowystinger previously approved these changes Mar 27, 2026

View reviewed changes

simplify and reduce image size

66e00c1

LFDanLu dismissed snowystinger’s stale review via 66e00c1 March 27, 2026 17:43

Apply suggestion from @yihuiliao

d39ee75

Co-authored-by: Yihui Liao <44729383+yihuiliao@users.noreply.github.com>

LFDanLu commented Mar 27, 2026

View reviewed changes

Merge branch 'main' of github.com:adobe/react-spectrum into docs_for_…

4d01017

…release

snowystinger approved these changes Mar 27, 2026

View reviewed changes

reidbarber approved these changes Mar 27, 2026

View reviewed changes

LFDanLu added this pull request to the merge queue Mar 28, 2026

Merged via the queue into main with commit 2fd3c81 Mar 28, 2026
29 checks passed

LFDanLu deleted the docs_for_release branch March 28, 2026 00:11


		Use the `orientation` option to arrange items horizontally or vertically. Provide the same `orientation` on the collection component so keyboard navigation matches the layout.

		```tsx render docs={docs.exports.ListLayoutOptions} links={docs.links} props={['gap', 'padding']} initialProps={{estimatedRowSize: 300, gap: 8, padding: 8, orientation: 'horizontal'}} propsObject="layoutOptions" wide

Conversation

LFDanLu commented Mar 25, 2026

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Mar 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rspbot commented Mar 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Mar 26, 2026

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

nwidynski commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu commented Mar 27, 2026

Uh oh!

nwidynski commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rspbot commented Mar 27, 2026

Uh oh!

rspbot commented Mar 27, 2026

Uh oh!

rspbot commented Mar 27, 2026

Uh oh!

rspbot commented Mar 27, 2026

react-aria-components

/react-aria-components:TableLayout

/react-aria-components:ListLayoutOptions

/react-aria-components:TableLayoutProps

@react-spectrum/s2

/@react-spectrum/s2:ListView

/@react-spectrum/s2:ListViewProps

@react-stately/layout

/@react-stately/layout:TableLayout

/@react-stately/layout:ListLayoutOptions

/@react-stately/layout:TableLayoutProps

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

nwidynski commented Mar 27, 2026 •

edited

Loading

nwidynski commented Mar 27, 2026 •

edited

Loading